# Cantieri - Manutenzione

Il software è progettato per gestire la manutenzione ed è organizzato in tre componenti principali:

- **Lista protocolli applicabili**, ossia l'insieme dei form creati dall'azienda per standardizzare le procedure di manutenzione. Ogni protocollo è un template che l'operatore può compilare durante la manutenzione.

- **Lista prodotti**, in cui i prodotti sono intesi come concetti astratti

- **Lista cantieri**, in cui vengono gestiti tutti gli artefatti, gli interventi e lo stato di manutenzione.

## Flusso operativo

Per implementare correttamente il sistema di manutenzione, è necessario seguire i seguenti passaggi in sequenza:

1. **Analizzare la composizione del prodotto**  
   Identificare mentalmente la struttura dell'impianto e i suoi componenti astratti.

2. **Creare i protocolli di manutenzione**  
   Definire i form standardizzati che gli operatori utilizzeranno per documentare gli interventi. Per informazioni dettagliate, consultare la [guida ai protocolli](../Protocolli/protocolli.md).

   **N.B.** il tipo di protocollo deve essere **Manutenzione**.

3. **Creare i prodotti astratti**  
   Dalla **Lista prodotti**, creare l'anagrafica dei prodotti inserendo codice e nome.

4. **Configurare gli "Extra per cantieri"**  
   Definire i campi personalizzabili che caratterizzeranno ogni istanza del prodotto (marca, modello, potenza, ecc.).

5. **Definire le installazioni** *(se necessario)*  
   Configurare l'installazione del prodotto per generare automaticamente i componenti durante la creazione degli artefatti.

6. **Associare i protocolli ai prodotti**  
   Collegare ogni protocollo al prodotto di riferimento specificando la periodicità degli interventi di manutenzione.

7. **Creare gli artefatti sul cantiere**  
   Generare le istanze concrete dei prodotti sul cantiere, valorizzando gli "Extra per cantieri" precedentemente configurati


## Idea iniziale
Prima di procedere con la configurazione del sistema, è fondamentale **visualizzare mentalmente la struttura finale** dell'impianto o dell'installazione da gestire, ragionando per **componenti astratti** piuttosto che per prodotti specifici.

## Distinzione tra prodotto astratto e artefatto concreto
Il sistema si basa su una **logica a due livelli**:

**1. Prodotto astratto (template)**
- Rappresenta la **categoria concettuale** del componente
- Definisce **cosa** compone l'impianto, non quale marca o modello specifico
- Esempio: "Punto luce" composto da → "Lampada", "Interruttore", "Cablaggio"

**2. Artefatto concreto (istanza)**
- Rappresenta l'**installazione fisica** sul cantiere
- Contiene le **caratteristiche specifiche** e i **riferimenti reali**
- Esempio: Lampada → Marca: Philips, Modello: Hue White, Potenza: 9W, Colore: Bianco caldo

## Esempio pratico di progettazione

Supponiamo di dover gestire la manutenzione di un **impianto di illuminazione**.

### **Fase 1 - Analisi della composizione**  
Identificare i macroelementi e i relativi componenti:
- **Punto luce** (macroelemento)
  - Lampada (componente)
  - Interruttore (componente)
  - Plafoniera (componente)

### **Fase 2 - Creazione dei protocolli di manutenzione**  
Prima di creare i prodotti, definire i protocolli che serviranno per documentare gli interventi di manutenzione.

Esempi di protocolli per l'impianto di illuminazione:
- **Controllo visivo lampade**: verifica funzionamento, pulizia, controllo temperatura
- **Verifica elettrica**: test continuità, misurazione tensione, controllo isolamento
- **Sostituzione lampada**: registrazione componente sostituito, motivazione, nuovi parametri

### **Fase 3 - Creazione dei prodotti astratti**  
Dalla **Lista prodotti**, creare un prodotto per ciascun componente identificato nell'analisi.
Nell'esempio del punto luce, occorre creare 4 prodotti: "Punto luce" (macroelemento), "Lampada", "Interruttore" e "Plafoniera" (componenti).

![nuovoprodotto](nuovoprodotto.png)

Per ogni prodotto inserire:
- **Codice**: identificativo univoco (es. LAMP-001, INT-001, PLAF-001)
- **Nome**: denominazione del prodotto (es. "Lampada", "Interruttore", "Plafoniera")

### **Fase 4 - Definizione degli "Extra per cantieri"**  
Gli **Extra per cantieri** sono i campi personalizzabili che permettono di specificare le caratteristiche tecniche di ogni istanza del prodotto installata sul cantiere. Questi parametri possono variare tra diverse installazioni dello stesso prodotto e possono essere modificati durante gli interventi di manutenzione.

![extracantieri](extrapercantieri.png)

La configurazione degli extra utilizza una tabella con le seguenti colonne:

- **Nome Campo**: denominazione del parametro (es. "Marca", "Modello", "Potenza")
- **Tipo**: tipologia di dato
  - **Testo**: per informazioni descrittive (marca, modello, colore)
  - **Numero**: per valori numerici (potenza, dimensioni)
  - **Check**: per parametri booleani (attivo/spento)
  - **Data**: per date di riferimento (anno installazione)
- **Obblig.**: indica se il campo è obbligatorio in fase di creazione dell'artefatto
- **UM** (Unità di Misura): specifica l'unità (kW, cm, °C, ecc.)
- **Valore di default**: valore preimpostato per velocizzare l'inserimento
- **Opzioni**: elenco di valori selezionabili (per campi a scelta multipla)

**Esempio di configurazione "Extra per cantieri" per il prodotto "Lampada":**

| Nome Campo | Tipo | Obblig. | UM | Valore di default | Opzioni |
|------------|------|---------|-----|-------------------|-------|
| Marca | Testo | ☑ | - | - | Philips, Beghelli |
| Modello | Testo | ☑ | - | - | - |
| Potenza | Numero | ☑ | kW | 9 | - |
| Temperatura colore | Testo | ☐ | °K | 3000 | 2700, 3000, 4000 |
| Anno installazione | Numero | ☐ | - | 2024 | - |
| Stato | Check | ☐ | - | Attivo | Attivo, Spento |

### **Fase 5 - Associazione dei protocolli di manutenzione**  
Nella sezione **Protocolli**, collegare i protocolli applicabili al prodotto specificando:
- Il protocollo da applicare
- La **periodicità** degli interventi (es. ogni 6 mesi, ogni anno, ogni giorno)

![protocolliprodotto](protocolliprodotto.png)

**N.B.** Il sistema calcola le manutenzioni successive a partire dalla **data della prima manutenzione effettuata** (che può essere anche un form compilato il primo giorno di installazione). La periodicità impostata viene quindi applicata in modo incrementale da questa data iniziale.

### **Fase 6 - Configurazione dell'installazione** *(opzionale)*  
La sezione **Installazione** permette di definire l'elenco dei componenti necessari per la sua installazione.
Utile quando un componente può essere montato in modalità differenti e con diversi componenti per ogni modalità.

Esempio per "Lampada":
- Installazione a soffitto
- Installazione a parete
- Installazione su palo

L'installazione è composta da:
- **Nome installazione**: configurazione del prodotto (es. "Standard", "Premium")
- **Componenti**: lista dei prodotti necessari con relative quantità

![installazione](installazione.png)

Procedura:
1. **Definire il nome dell'installazione**
   - Nel campo **Installazione**, inserire un nome descrittivo (es. "Standard", "Premium", "Doppia")
   - Se non si inserisce alcun nome, viene creata l'installazione **"default"**

2. **Cliccare su "Crea modello d'installazione"**
   - Si apre una tabella per definire i componenti

3. **Aggiungere i componenti nella tabella**
   - Cliccare su **+ Nuova** per aggiungere ogni componente
   - Aggiungere per ogni riga l'**Articolo** dalla lista dei prodotti
4. **Salvare la configurazione**

**Nota:** Il sistema calcola le quantità per **1 unità** del prodotto principale.

---

Esempio pratico - Prodotto: "Punto Luce"

**Installazione 1: "default"** 

| Articolo | Q.tà Cal. | UM |
|----------|-----------|-----|
| Lampada LED 9W | 1 | PZ |
| Interruttore | 1 | PZ |
| Plafoniera | 1 | PZ |
| Cavo elettrico 5MT | 1 | PZ |

**Installazione 2: "Doppia"**

| Articolo | Q.tà Cal. | UM |
|----------|-----------|-----|
| Lampada LED 9W | 1 | PZ |
| Lampada LED 9W | 1 | PZ |
| Interruttore doppio | 1 | PZ |
| Plafoniera doppia | 1 | PZ |
| Cavo elettrico 5MT | 1 | PZ |

**Funzionalità chiave:**  
Configurando un'installazione, alla creazione di un artefatto sul cantiere il sistema **genera automaticamente tutti i componenti associati**, eliminando la necessità di inserirli manualmente

---

### **Fase 7 - Creazione del cantiere**  
Dalla **Lista cantieri**, creare un nuovo cantiere inserendo la **Denominazione** (campo obbligatorio). Gli altri dati possono essere completati successivamente.

### **Fase 8 - Creazione degli artefatti sul cantiere**  
Accedere alla sezione **Artefatti** del cantiere per configurare l'impianto.

**Logica di denominazione degli artefatti**

Il nome dell'artefatto principale (macroelemento) deve identificare un **insieme di elementi omogenei**, non un singolo elemento.

**Esempi corretti:**
- "Pannelli Fotovoltaici Tetto Est" → raggruppa 20 pannelli
- "Condizionatori Uffici" → raggruppa 8 climatizzatori
- "Estintori Edificio A" → raggruppa 12 estintori

**Esempi errati:**
- "Pannello Fotovoltaico #1" → troppo specifico, questo è un componente
- "La Lampada" → troppo generico e singolare

Procedura di creazione degli artefatti:

#### **Step 1 - Creazione del macroelemento**

![artefattopadre](artefattopadre.png)

1. Dalla sezione **Artefatti** del cantiere, cliccare su **+ Nuovo**
2. Il sistema mostra il messaggio "Nessun elemento disponibile"
3. Compilare il form di creazione del macroelemento:
   - **Nome**: denominazione del raggruppamento (es. "Condizionatori Uffici - Edificio A")
   - **Prodotto di riferimento**: selezionare il prodotto astratto (es. "Condizionatore")
4. Salvare

#### **Step 2 - Configurazione degli elementi interni**

![secondoartefatto](secondoartefatto.png)

1. **Fare doppio click** sul macroelemento appena creato
2. Cliccare su **Aggiungi** per creare ogni singolo elemento
3. Nel form di aggiunta elemento compilare:
    - **Nome**: identificativo specifico dell'elemento (es. "Condizionatore 1", "Condizionatore Ufficio 101")
    - **Installazione**: selezionare il tipo di installazione configurato
    - Se si seleziona un'installazione (es. "default", "Monosplit Standard"), i componenti verranno generati automaticamente nella vista successiva
    - È possibile non selezionare alcuna installazione e aggiungere i componenti manualmente
    - **Extra per cantieri**: compilare tutte le proprietà specifiche ereditate dal prodotto di riferimento
    - Se sono stati configurati **valori di default**, i campi vengono **precompilati automaticamente**
    - Esempio: Marca (precompilato: Mitsubishi)
4. Cliccare su "Salva"

**N.B.** se **non** si seleziona un tipo di installazione durante la creazione dell'artefatto, i componenti dell'artefatto non saranno generati!

![aggiungiinstallazione](aggiungiinstallazione.png)

#### **Step 3 - Visualizzazione degli elementi**

Una volta salvato, l'elemento compare nella lista. Il sistema offre **due modalità di visualizzazione**:

1. **Vista Tabella** 
   - Visualizzazione compatta con tutti gli elementi in formato tabellare
   - Utile per filtrare gli elementi per proprietà (esempio stato)

   ![tabella](formatotabella.png)

2. **Vista Card**
   - Visualizzazione a schede con le informazioni principali in evidenza
   - Utile per una consultazione più visuale

   ![card](formatocard.png)

#### **Step 4 - Accesso ai componenti**

Per visualizzare e gestire i componenti di un artefatto:

1. **Cliccare sull'artefatto** (singolo click sulla card o doppio click sulla riga)
2. Se è stata selezionata un'installazione durante la creazione:
   - I componenti sono già presenti automaticamente
   - È possibile visualizzare e modificare le proprietà di ogni componente

3. Se NON è stata selezionata un'installazione:
   - È necessario aggiungere manualmente i componenti
   - Cliccare su **+ Nuovo** per aggiungere ogni componente

#### **Step 5 - Gestione delle proprietà dei componenti**

**Precompilazione automatica dei componenti**  
Quando si crea un artefatto selezionando un'installazione, il sistema genera automaticamente tutti i componenti configurati nell'installazione. Se per questi componenti sono stati definiti **valori di default** nelle proprietà "Extra per cantieri", questi valori vengono **precompilati automaticamente**.

![dettaglicomponente](dettaglicomponenti.png)

**Modifica delle proprietà durante la manutenzione**

Le proprietà dei componenti **non sono statiche**: possono essere modificate nel tempo durante gli interventi di manutenzione, per registrare:
- **Sostituzioni di componenti**
- **Modifiche tecniche**
- **Cambiamenti di posizione**
- **Aggiornamenti dello stato**

Tutte le modifiche vengono **automaticamente tracciate nello storico**, permettendo di ricostruire l'evoluzione del componente nel tempo

#### Step 6 - Storico Modifiche
Lo **Storico** è una funzionalità fondamentale del sistema che registra automaticamente **tutte le modifiche** apportate agli artefatti e ai loro componenti nel tempo. Ogni variazione delle proprietà viene tracciata con data, ora e dettagli della modifica, garantendo una **tracciabilità completa** dell'evoluzione dell'impianto.

Per visualizzare lo storico delle modifiche di un artefatto cliccare sul pulsante **"Mostra storico"**

![storicomodifiche](storicomodifiche.png)

**Importante:** Lo storico visualizza uno **snapshot per giornata**, mostrando:
- Lo **stato iniziale** dell'artefatto alla data di creazione
- Lo **stato finale** dell'artefatto alla fine di ogni giornata in cui sono state effettuate modifiche

Questa logica permette di **evitare la visualizzazione di errori accidentali** o modifiche temporanee corrette nello stesso giorno.

## Gestione degli Interventi di Manutenzione
Dopo aver configurato i prodotti, gli artefatti e i protocolli, il sistema permette di **registrare e gestire gli interventi di manutenzione** effettivi sugli artefatti installati sul cantiere.

### Accesso allo storico interventi

Per visualizzare e gestire gli interventi di manutenzione di un artefatto:

1. Accedere alla sezione **Artefatti** del cantiere
2. Selezionare l'artefatto o il componente desiderato
3. Cliccare su **"Manutenzione"**

![storicointerventi](storicointerventi.png)

La schermata mostra una tabella con tutti gli interventi registrati, contenente le seguenti informazioni:
- **Protocollo applicato**: il tipo di manutenzione effettuata (es. "Manutenzione periodica condizionatore")
- **Data intervento**: quando è stato eseguito l'intervento (es. 08/11/2025)
- **Prossima data**: quando è prevista la prossima manutenzione (calcolata automaticamente in base alla periodicità, es. 08/05/2026 per manutenzione tra 6 mesi)
- **Operatore**: chi ha effettuato l'intervento (es. "Mario Rossi")

Per ogni intervento registrato, sono disponibili le seguenti azioni:

- **Modifica**: permette di modificare i dati dell'intervento (data, operatore, campi del protocollo)
- **Elimina**: rimuove l'intervento dallo storico
- **Visualizza dettagli intervento**: apre la schermata con tutti i dettagli della compilazione del protocollo
- **Esporta come PDF**: genera un documento PDF scaricabile della manutenzione da inviare ai clienti
- **+ Nuovo intervento**: crea un nuovo intervento di manutenzione

Il software offre **due modalità** per creare e compilare un intervento di manutenzione:

- **Compilazione da software**

![nuovointervento](interventobackoffice.png)

- **Compilazione da Web App**